Docusaurus 網站開發技術指南

本文檔整理了關於 Docusaurus 網站開發的實用技術知識，包括樣式設定、響應式設計、SEO優化等方面的最佳實踐。

CSS 樣式設定

Docusaurus CSS 類別來源

Docusaurus 中的 CSS 樣式主要來自兩個地方：

Docusaurus 官方內建 CSS class：
- 例如 hero 和 hero--primary 是來自 Docusaurus 預設的主題樣式
- 通常定義在 node_modules/@docusaurus/theme-classic/lib/theme 或最終 build 完會打包進 .docusaurus 裡
- 控制整個頁首（Hero Section）的樣式，例如背景色、文字色等
- 想自訂這些，通常是覆寫 custom.css 或 theme 的 override
專案自己的 CSS Module：
- 例如 styles.heroBanner 中的 styles 是 import 進來的 CSS Module
- heroBanner 是這個 CSS Module 中定義的一個 class
- 通常在 src/pages/index.module.css 中定義
- 在 src/pages/index.js 或 src/pages/index.jsx 中引入：import styles from './index.module.css';

自定義 Hero 區塊背景色

要修改 Hero 區塊的背景色或圖片，需要覆寫官方的 hero--primary 這個 class。正確做法有兩種：

使用內嵌 style 控制（推薦新手使用）：

<header
  className={clsx('hero hero--primary', styles.heroBanner)}
  style={{
    backgroundImage: 'url(/img/banner.png)',
    backgroundSize: 'cover',
    backgroundPosition: 'center',
  }}
>

使用 Docusaurus 官方建議的 CSS 變數：

.hero--primary {
  --ifm-hero-background-image: url('/img/banner.png');
  background-image: var(--ifm-hero-background-image);
  background-size: cover;
  background-position: center;
}

適配白天/黑夜模式

在 Docusaurus 中，[data-theme='light'] 和 [data-theme='dark'] 是掛在 <html> 標籤上的，用於控制白天/黑夜模式的樣式。正確的寫法是：

[data-theme='light'] .hero--primary {
  background-color: #ffffff;
  color: #000000; /* 黑色字 */
  background-size: cover;
  background-position: center;
}

[data-theme='dark'] .hero--primary {
  background-color: #282a36;
  color: #ffffff; /* 白色字 */
  background-size: cover;
  background-position: center;
}

Hero 區塊設計

響應式 Hero 設計

創建一個左右布局的 Hero 區塊，並支持響應式設計：

HTML 結構：

<header className={clsx('hero hero--primary', styles.heroBanner)}>
  <div className="heroWrapper">
    <div className="heroLeft">
      <h1 className="heroTitle">COVIA</h1>
    </div>
    <div className="heroRight">
      <p className="heroSubtitle">開啟智慧之路，從每一次探索開始。</p>
    </div>
  </div>
</header>

CSS 樣式：

.heroBanner {
  padding: 6rem 2rem;
}

.heroWrapper {
  display: flex;
  align-items: center;
  justify-content: space-between;
  max-width: 1200px;
  margin: 0 auto;
}

.heroLeft {
  flex: 1;
  text-align: left;
}

.heroRight {
  flex: 1;
  text-align: left;
}

.heroTitle {
  font-family: 'Anton', sans-serif;
  font-size: 8rem;
  font-weight: 400;
  line-height: 1.1;
  margin: 0;
}

.heroSubtitle {
  font-family: 'Noto Sans TC', sans-serif;
  font-size: 1.5rem;
  font-weight: 400;
  margin: 0;
  max-width: 400px;
}

/* 響應式設計 */
@media (max-width: 768px) {
  .heroWrapper {
    flex-direction: column;
    text-align: center;
  }

  .heroLeft,
  .heroRight {
    flex: none;
  }

  .heroTitle {
    font-size: 4rem;
  }

  .heroSubtitle {
    margin-top: 2rem;
    font-size: 1.25rem;
  }
}

解決文本排版問題

當中文文本在小容器中出現奇怪的換行和縮排問題時，可以使用以下 CSS 屬性：

.heroSubtitle {
  text-align: left;
  word-break: break-word; /* 中文也能斷行 */
  white-space: normal; /* 確保不會一整段卡住 */
  line-height: 1.6;
}

在 Hero 區下方添加宣言區

正確的結構應該是：

<header className="hero hero--primary">
  <!-- Hero 區（大標 + 小標） -->
</header>

<section className="heroDeclaration">
  <!-- 宣言區（短句/呼籲語） -->
</section>

<main>
  <!-- 主要內容區（功能介紹、最新消息、產品亮點等等） -->
</main>

CSS 樣式：

.heroDeclaration {
  padding: 4rem 0;
  background-color: var(--ifm-background-color);
  text-align: center;
}

.heroDeclarationInner {
  max-width: 800px;
  margin: 0 auto;
}

.heroDeclarationText {
  text-align: left;
  font-size: 1.5rem;
  font-weight: 400;
  line-height: 1.8;
  margin: 0;
  white-space: normal;
  word-break: break-word;
}

Google 字體引入

在 Docusaurus 中引入 Google 字體

在 docusaurus.config.js 中添加 stylesheets：

module.exports = {
  // 其他設定...
  stylesheets: [
    {
      href: 'https://fonts.googleapis.com/css2?family=Anton&display=swap',
      type: 'text/css',
    },
  ],
};

在 CSS 中使用字體：

.heroTitle {
  font-family: 'Anton', sans-serif;
}

字體備援設定

如果使用的字體不支持中文，可以設定備援字體：

.heroTitle {
  font-family: 'Anton', 'Noto Sans TC', sans-serif;
}

這樣遇到中文字時，會自動套用 Noto Sans TC，整體更一致。

頁腳設計與社交媒體圖標

Docusaurus 頁腳配置

Docusaurus 的 Footer 配置在 docusaurus.config.js 中，有兩種類型：

簡單型（simple）
多欄型（multi-column）

不能混合使用這兩種類型。正確的配置方式：

footer: {
  style: 'dark',
  links: [
    {
      title: '分享',
      items: [
        {
          html: `
            <div class="footer-social-icons">
              <a href="https://social-plugins.line.me/lineit/share?url=https://你的網址" target="_blank" rel="noopener noreferrer">
                <img src="https://cdn.simpleicons.org/line/00C300" alt="Share on LINE" />
              </a>
              <!-- 其他社交媒體圖標 -->
            </div>
          `,
        },
      ],
    },
  ],
  copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
},

社交媒體圖標樣式

為社交媒體圖標創建獨立的圓形背景：

.footer-social-icons {
  display: flex;
  gap: 1rem;
  justify-content: center;
  align-items: center;
  flex-wrap: wrap;
}

.footer-social-icons a {
  width: 50px;
  height: 50px;
  background-color: white; /* 小圓形底色 */
  border-radius: 50%;
  display: flex;
  align-items: center;
  justify-content: center;
  box-shadow: 0 2px 5px rgba(0,0,0,0.1); /* 小陰影讓更立體 */
  transition: transform 0.2s ease;
}

.footer-social-icons a:hover {
  transform: scale(1.1); /* 滑鼠移過去稍微放大 */
}

.footer-social-icons img {
  width: 24px;
  height: 24px;
}

/* 暗色模式適配 */
[data-theme='dark'] .footer-social-icons a {
  background-color: #333333;
}

/* 暗色模式下圖標變白色 */
[data-theme='dark'] .footer-social-icons a img {
  filter: brightness(0%) invert(1);
  opacity: 0.9; /* 微微降低亮度，看起來更舒服 */
}

SEO 優化策略

網站標題與描述的最佳實踐

在 Docusaurus 中，有幾個關鍵的 SEO 設定：

config.js 中的 title 和 tagline：

const config = {
  title: 'COVIA 知識共享平台',
  tagline: '探索知識、實踐應用、推動開源的成長平台。',
  favicon: 'img/favicon.ico',
}

頁面中的 Layout title 和 description：

<Layout
  title="探索AI與網站建置的第一站"
  description="從AI、編程到網站建置與開源實作，讓每個挑戰成為你的實力。"
>

標題設計原則

避免關鍵字堆砌：
- 不好的例子：COVIA｜AI｜編程｜網站建置｜邏輯理論｜落地應用｜部署實作｜開源分享
- 好的例子：COVIA｜探索AI、編程與網站建置的知識共享平台
標題長度控制：
- 控制在 50-60 字元以內，避免 Google 截斷顯示
自然語意優先：
- 讓標題讀起來像一個自然的句子，而不是關鍵字列表

Layout title 與 config title 的關係

在 Docusaurus 中，最終的 <title> 標籤會自動組合成：Layout Title | Site Title

Layout title：頁面的個別標題，SEO 影響最大
config.js 中的 title：網站整體名稱，輔助作用

最佳實踐是：

Layout title 寫每個頁面的個別主題
Site title (config.js) 寫整個網站品牌名
tagline 不會直接影響 SEO，主要用於頁面顯示

Open Graph 與社交媒體分享

Open Graph 標籤設置

Open Graph 標籤用於控制網站在社交媒體上分享時的預覽效果：

<!-- Open Graph Meta Tags (for Facebook, LINE, Discord, Telegram, Threads) -->
<meta property="og:type" content="website" />
<meta property="og:title" content="COVIA｜探索AI、編程與網站建置的知識共享平台" />
<meta property="og:description" content="從AI、編程到網站建置與開源實作，讓每個挑戰成為你的實力。" />
<meta property="og:url" content="https://covia.com/" />
<meta property="og:image" content="https://covia.com/img/og-image.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:site_name" content="COVIA" />

<!-- Twitter Card Meta Tags (for X) -->
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="COVIA｜探索AI、編程與網站建置的知識共享平台" />
<meta name="twitter:description" content="從AI、編程到網站建置與開源實作，讓每個挑戰成為你的實力。" />
<meta name="twitter:image" content="https://covia.com/img/og-image.png" />
<meta name="twitter:url" content="https://covia.com/" />

在 Docusaurus 中添加 Open Graph 標籤

有兩種方法可以在 Docusaurus 中添加 Open Graph 標籤：

全站統一設定（在 docusaurus.config.js 中）：

themeConfig: {
  // ...其他設定
  metadata: [
    { name: 'description', content: '從AI、編程到網站建置與開源實作，讓每個挑戰成為你的實力。' },
    { property: 'og:type', content: 'website' },
    { property: 'og:title', content: 'COVIA｜探索AI、編程與網站建置的知識共享平台' },
    // ...其他 meta 標籤
  ],
},

單頁個別設定（在頁面組件中）：

import Head from '@docusaurus/Head';

export default function Home() {
  const { siteConfig } = useDocusaurusContext();
  return (
    <Layout
      title="COVIA｜探索AI、編程與網站建置的知識共享平台"
      description="從AI、編程到網站建置與開源實作，讓每個挑戰成為你的實力。"
    >
      <Head>
        <meta property="og:type" content="website" />
        <meta property="og:title" content="COVIA｜探索AI、編程與網站建置的知識共享平台" />
        {/* ...其他 meta 標籤 */}
      </Head>
      <HomepageHeader />
      <main>...</main>
    </Layout>
  );
}

分享圖片最佳實踐

建議尺寸：1200 × 630 px（FB、LINE官方推薦的比例）
圖檔大小：小於 300KB 最佳，載入快
圖片內容：簡潔＋品牌名＋一個短slogan（不要寫太多文字）
設計建議：LOGO + 「COVIA｜知識共享平台」＋簡單背景

語意搜索趨勢

現代搜索引擎已經從「關鍵字比對」轉向「語意理解」：

過去：關鍵字匹配（keyword matching）、「有這個字」就給分
現在/未來：語意理解（semantic matching）、「這段話意圖是什麼」才給分

最佳實踐：

聚焦在主題明確、敘述自然、語意清晰的內容建置
往「語意匹配、解決使用者意圖」的方向優化
不需要過度依賴 TAG 和關鍵字堆砌

目錄​

CSS 樣式設定​

Docusaurus CSS 類別來源​

自定義 Hero 區塊背景色​

適配白天/黑夜模式​

Hero 區塊設計​

響應式 Hero 設計​

解決文本排版問題​

在 Hero 區下方添加宣言區​

Google 字體引入​

在 Docusaurus 中引入 Google 字體​

字體備援設定​

頁腳設計與社交媒體圖標​

Docusaurus 頁腳配置​

社交媒體圖標樣式​

SEO 優化策略​

網站標題與描述的最佳實踐​

標題設計原則​

Layout title 與 config title 的關係​

Open Graph 與社交媒體分享​

Open Graph 標籤設置​

在 Docusaurus 中添加 Open Graph 標籤​

分享圖片最佳實踐​

語意搜索趨勢​

目錄